Skip to content

feat: add exact refetch targeting and improve utils.refetch() behavior #552

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 7 commits into from
Oct 27, 2025
Merged

feat: add exact refetch targeting and improve utils.refetch() behavior #552

merged 7 commits into from
Oct 27, 2025
+404 −85

Conversation

@lucasweng
Copy link
Contributor

@lucasweng lucasweng commented Sep 14, 2025 •
edited by KyleAMathews
Loading

Resolves #537

Summary

  • Implemented exact query key targeting to prevent unintended cascading refetches of related queries
  • Changed utils.refetch() to bypass enabled: false for imperative control (matches TanStack Query hook behavior)
  • Returns QueryObserverResult from utils.refetch() for better DX
  • Removed refetchType option - not needed with exact targeting via observer

Key Changes

  1. Exact targeting: Uses queryObserver.refetch() which targets only this collection (no cascade)
  2. Bypasses enabled: false: Supports manual fetch patterns like button-triggered fetches and error recovery via clearError()
  3. Better return type: Returns QueryObserverResult instead of void so users can inspect the result
  4. Simplified API: Removed refetchType since exact targeting via observer makes it unnecessary

Test Plan

  • Tests pass locally
  • Package builds successfully
  • Added tests for clearError() exact targeting
  • Added tests for throwOnError behavior
  • Added test for enabled: false bypass

@changeset-bot
Copy link

changeset-bot bot commented Sep 14, 2025 •
edited
Loading

🦋 Changeset detected

Latest commit: d199a7a

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages
Name Type
@tanstack/query-db-collection Patch
@tanstack/db-example-react-todo Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@pkg-pr-new
Copy link

pkg-pr-new bot commented Sep 14, 2025 •
edited
Loading

More templates

@tanstack/angular-db

npm i https://pkg.pr.new/@tanstack/angular-db@552

@tanstack/db

npm i https://pkg.pr.new/@tanstack/db@552

@tanstack/db-ivm

npm i https://pkg.pr.new/@tanstack/db-ivm@552

@tanstack/electric-db-collection

npm i https://pkg.pr.new/@tanstack/electric-db-collection@552

@tanstack/query-db-collection

npm i https://pkg.pr.new/@tanstack/query-db-collection@552

@tanstack/react-db

npm i https://pkg.pr.new/@tanstack/react-db@552

@tanstack/rxdb-db-collection

npm i https://pkg.pr.new/@tanstack/rxdb-db-collection@552

@tanstack/solid-db

npm i https://pkg.pr.new/@tanstack/solid-db@552

@tanstack/svelte-db

npm i https://pkg.pr.new/@tanstack/svelte-db@552

@tanstack/trailbase-db-collection

npm i https://pkg.pr.new/@tanstack/trailbase-db-collection@552

@tanstack/vue-db

npm i https://pkg.pr.new/@tanstack/vue-db@552

commit: d199a7a

KyleAMathews and others added 2 commits October 24, 2025 07:06
@KyleAMathews
Merge branch 'main' into issue-537
7ec93aa
@KyleAMathews @claude
refactor: make utils.refetch() bypass enabled: false and remove refet…
3438c84 
…chType

Changes:
- Use queryObserver.refetch() for all refetch calls (both utils and internal handlers)
- Bypasses enabled: false to support manual fetch patterns (matches TanStack Query hook behavior)
- Fixes clearError() to work even when enabled: false
- Return QueryObserverResult instead of void for better DX
- Remove refetchType option - not needed with exact targeting via observer
- Add tests for clearError() exact targeting and throwOnError behavior
- Update docs to clarify refetch semantics

With exact targeting via queryObserver, refetchType filtering doesn't add value.
Users always want their collection data refetched, whether from utils.refetch()
or internal mutation handlers.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@KyleAMathews KyleAMathews changed the title feat: add exact refetch targeting and refetchType option feat: add exact refetch targeting and improve utils.refetch() behavior Oct 24, 2025
@KyleAMathews
Copy link
Collaborator

Hey @lucasweng! Sorry for not getting to this for so long! I/we somehow missed it.

Thanks for tackling this issue. I reviewed your PR and made some refinements based on a careful analysis of the requirements and TanStack Query's behavior. Here's what changed:

Changes Made

  1. Changed utils.refetch() to use queryObserver.refetch() instead of queryClient.refetchQueries()

This was the key insight: we need different behavior for imperative refetch vs batch refetch operations.

  1. Removed refetchType option

After discussion, we realized refetchType doesn't add value with exact targeting:

  • With exact: true, we're already targeting just this specific collection (no cascade)
  • Users always want their collection data refetched, whether from explicit utils.refetch() calls or after mutations
  • The refetchType filter made sense for preventing cascades in batch operations, but with exact targeting it's unnecessary
  1. Changed return type to QueryObserverResult
  • Returns the query result instead of void so users can inspect the result
  • Better DX and more aligned with hook behavior
  1. Added more comprehensive tests
  • Test for clearError() using exact targeting
  • Test for throwOnError propagation
  • Test for enabled: false bypass behavior

The Core Issue

The original issue was about preventing cascade refetches. Your solution with exact: true solved that perfectly! The additional changes ensure
that imperative refetch() calls work as users expect (bypassing enabled: false like hooks do).

Let me know if you have any questions about these changes!

@lucasweng
Copy link
Contributor Author

Hey @KyleAMathews, appreciate you taking the time to review this! No worries at all, I know the team's been working on a lot of features.

Thanks for the clear explanation of the refinements! The queryObserver.refetch approach makes way more sense for better DX and bypassing enabled: false. And yeah, you're right about refetchType. With exact targeting, it's redundant.

Just pushed d199a7a to fix a type error in query.test. 🙏🏻

@KyleAMathews
Copy link
Collaborator

Thanks!

@KyleAMathews KyleAMathews merged commit c2a5c28 into TanStack:main Oct 27, 2025
6 checks passed
@github-actions github-actions bot mentioned this pull request Oct 27, 2025
Merged
@github-actions
Copy link
Contributor

🎉 This PR has been released!

Thank you for your contribution!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Make QueryCollection refetch() target exact query only

2 participants

@lucasweng @KyleAMathews